SOLR-18212: Migrate PackageAPI endpoints from @EndPoint/@Command to JAX-RS by epugh · Pull Request #4178 · apache/solr

epugh · 2026-03-02T19:31:31Z

Migrates org.apache.solr.pkg.PackageAPI from Solr's homegrown @EndPoint/@Command dispatch to standard JAX-RS annotations, consistent with other V2 APIs (ClusterFileStore, ZookeeperRead, ClusterProperty).

This has a pretty hefty update to the patterns, but I thought it was better to do it now while v2 api's are "experimental".

New REST endpoints

The command-based POST pattern is replaced with RESTful routes. Note the collection is now plural (/cluster/packages), matching the v2 API path conventions used elsewhere:

Old	New
`GET /cluster/package`	`GET /cluster/packages`
`GET /cluster/package/{name}`	`GET /cluster/packages/{name}` (now returns 404 if the package doesn't exist, instead of silently returning an empty result)
`POST /cluster/package {"add": {"package":"p","version":"v","files":[...]}}`	`POST /cluster/packages/{name}/versions`
`POST /cluster/package {"delete": {"pkg":"p","version":"v"}}`	`DELETE /cluster/packages/{name}/versions/{version}`
`POST /cluster/package {"refresh": "name"}`	`POST /cluster/packages/{name}/refresh`
(internal only, used by `refresh` for node-local reload)	`POST /cluster/packages/{name}/refresh?localOnly=true`
(internal only, used to make a node catch up to a ZK version)	`POST /cluster/packages/sync?expectedVersion=N`

The two internal-only rows replace an earlier version of this PR that smuggled the same inter-node signals onto GET /cluster/packages via refreshPackage/expectedVersion query params — a GET request shouldn't have side effects. localOnly mirrors the existing localDelete param on ClusterFileStoreApis.deleteFile.

Key structural changes

PackageAPI — new JAX-RS implementation (extends JerseyResource implements PackageApis); replaces the old Edit/Read inner classes (~220 lines removed)
PackageStore — renamed from the old PackageAPI; now clearly a ZK data/state holder (Packages, PkgVersion, ZK watcher), not an endpoint class. THIS WAS A BIG REFACTORING
solr/api module — new PackageApis.java (JAX-RS interface), AddPackageVersionRequestBody.java, and two response types instead of one: ListPackagesResponse (the GET /cluster/packages collection response, map-keyed by package name) and GetPackageResponse (the GET /cluster/packages/{name} single-resource response, a flat object for just that package) — matching the List<Resource>Response/Get<Resource>Response naming and shape convention used by ListAliasesResponse/GetAliasByNameResponse and similar pairs elsewhere in the v2 API. OAS generation produces PackageApi SolrJ request classes automatically.
PackageAPITest — integration test using SolrCloudTestCase (ZK required) with generated PackageApi SolrJ request classes
TestPackages — updated to use new endpoints; error path changed from /details[0]/errorMessages[0] to /msg
package-manager-internals.adoc — updated endpoint reference and curl examples
dev-docs/apis-v2-conventions.adoc — added a new "Listing vs. Single-Resource Responses" section documenting the List<Resource>Response/Get<Resource>Response convention, since this PR is the first to need it spelled out explicitly

- Replace PackagePayload.AddVersion with AddPackageVersionRequestBody - Move package name from body to URL: POST /cluster/package/{name}/versions - Replace delete command pattern with DELETE /cluster/package/{name}/versions/{version} - Replace refresh command with POST /cluster/package/{name}/refresh - Update errPath in testAPI from /details[0]/errorMessages[0] to /msg - Remove all add.pkg assignments (pkg now lives in URL path) - Replace add.pkg references in verifyComponent() with literal package name strings - Update import: remove PackagePayload, add AddPackageVersionRequestBody (sorted) Co-authored-by: Copilot <[email protected]>

Co-authored-by: epugh <[email protected]>

…sponse.error field Co-authored-by: epugh <[email protected]>

Co-authored-by: epugh <[email protected]>

… style

gerlowskija · 2026-04-03T19:45:12Z

Is there a JIRA ticket associated with this change @epugh?

epugh · 2026-04-03T20:33:51Z

Is there a JIRA ticket associated with this change @epugh?

No, because I viewed it as "just a refactoring and no one will notice....", and that I was hoping there were no debates that would require a JIRA to hash out!

gerlowskija · 2026-04-03T20:00:38Z

+authors:
+  - name: Eric Pugh
+links:
+- name: PR#4178


[0] Probably worth having a JIRA reference for this guy, even if it's just a tie-back to one of the v2 umbrella tickets? It's changing APIs and stuff, so worth tracking in more than just the PR description I'd imagine.

gerlowskija · 2026-04-06T14:35:54Z

-    public int hashCode() {
-      return Objects.hash(version);
-    }
+    final var request =


[Q] Is there a reason you're not using the auto-generated SolrJ type here? We should have one now that the API is JAX-RS!

If this was an intentional decision made to prevent scope-creep, I'm fine with that. Just making sure it's not oversight.

so many places to update... I suspect in the future we need to do a "Check each GSR for fitness" check ;-)

Like I said, I think not doing these bits in the same PR is a totally valid choice. I don't want to add extra steps that'd apply to all these PRs. But since the lines were changed in this PR already I wanted to check that it was an intentional choice is all 🤷

…kageapi-to-jax-rs

Rename PackageAPI to ClusterPackage to follow naming pattern of other V2 apis.

Add test, revamp description.

epugh · 2026-04-25T16:47:57Z

@gerlowskija I think I am ready for another review. I renamed PackageAPI to ClusterPackage to not conflict with PackageApis, but not married to that name! I am updating the spreadsheet.

epugh · 2026-08-28T13:37:32Z

@gerlowskija I reopened this, and will try and give it some love today.. Thanks for the LGTM....

…kageapi-to-jax-rs

…i/cluster/packages and errors.

epugh · 2026-08-28T18:55:32Z

@gerlowskija this is ready for review!!!!

epugh · 2026-08-28T19:38:10Z

Tests, both unit and itest (bats) pass...

jaykay12 · 2026-10-16T23:33:40Z

@epugh I am planning to review this PR, can you make this one ready for review by rebasing with latest main?

epugh · 2026-10-17T16:11:05Z

@jaykay12 I added you as a collaborate to my epugh/solr... which I think lets you push to this repo? I hope this makes it easier as I have a couple of in progress ones you may wan tot pick up!

…n the Package v2 API - Move the inter-node refresh/sync fan-out off GET /cluster/packages (which was mutating state via refreshPackage/expectedVersion query params) onto POST endpoints: a localOnly flag on the existing /refresh action (mirroring ClusterFileStoreApis.deleteFile's localDelete), and a new /sync action. - getPackage() now returns 404 for an unknown package, matching deletePackageVersion/refreshPackage's existing NOT_FOUND behavior. - Split the single-package GET response into its own flat shape (GetPackageResponse) instead of reusing the list endpoint's map-shaped response filtered to one entry, and renamed both response classes to match the List<Resource>Response / Get<Resource>Response convention used elsewhere (aliases, cluster properties, schema fields). - Extracted the duplicated node-broadcast loop in ClusterPackage into a shared helper. - Documented the List/Get response-naming convention in dev-docs/apis-v2-conventions.adoc. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_019kzScQszwRcG4S7kA5Pa8b

PackageManager's deploy --update and undeploy flows were still POSTing a v1-style JSON command body ({"refresh": "name"}) to /api/cluster/packages, left over from before the JAX-RS migration. The new endpoint doesn't accept a body at all - it's POST /cluster/packages/{name}/refresh - so these calls were silently broken against the migrated server. Switch both call sites to the generated PackageApi.RefreshPackage client, matching how DeletePackageVersion/AddPackageVersion were already migrated elsewhere in this file. Removes the now-unused PackageUtils.PACKAGE_PATH constant. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_019kzScQszwRcG4S7kA5Pa8b

@command

…kage API shape testPayload()'s @EndPoint/@command fixture (path /cluster/package, an AddVersion bean with pkg/version/files) mirrored the now-deleted v1 Package API almost exactly, which reads as leftover Package API code rather than a generic framework test. Rename to /foos/FooVersion/myfoo so it's obviously just a test fixture. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_019kzScQszwRcG4S7kA5Pa8b

ReferenceEquality flagged schemas[0] != schemas[1] as a likely mistake, but the test intentionally checks whether the core picked up a new IndexSchema instance after the package version bump - identity, not value equality, is what's being verified. Suppress with the same pattern used elsewhere in the codebase for intentional identity checks (SolrConfig.java, CachingDirectoryFactory.java). Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_019kzScQszwRcG4S7kA5Pa8b

…sterPackage addPackageVersion and deletePackageVersion each inlined the same "deserialize packages.json bytes, fall back to a fresh Packages on missing/invalid data, then copy()" block, and the same isEnabled()/BAD_REQUEST guard. Extracted both into PackageStore (parseForUpdate, requireEnabled) since they operate on PackageStore's own data/mapper, and call them from both atomicUpdate lambdas. Also noted, via a one-line comment, why PackageManager's undeploy refresh call site keeps a broader catch(Exception) than its sibling deploy call site (it still wraps a postJsonToSolr call that declares throws Exception). Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_019kzScQszwRcG4S7kA5Pa8b

epugh · 2026-10-28T17:17:42Z

@jaykay12 would love your review! I think this is ready for merging.

jaykay12

Let me know if this minor plan change makes sense?

Ask is to just isolate the { renaming of PackageAPI -> PackageStore } in a follow-up PR.

jaykay12 · 2026-10-29T18:52:30Z

+/**
+ * Holds package data loaded from ZooKeeper ({@code /solr/packages.json}) and manages ZK watchers.
+ */
+public class PackageStore {


this class is majorly (PackageAPI - {code no longer needed}), please correct me if i am wrong.

[suggestion] should we be splitting up PRs in those case, so that review stays easier & any unintentional change gets caught.

This PR could have been just pure migration & removal of deprecated stuff from PackageAPI class. In subsequent follow-up this renaming could have been attempted?

This is my pure thought, with this minor change, the PR size would have reduced by atleast 8-9 files.

jaykay12 · 2026-10-29T19:13:06Z

+  @Override
+  @PermissionName(PACKAGE_EDIT_PERM)
+  public SolrJerseyResponse addPackageVersion(
+      String packageName, AddPackageVersionRequestBody requestBody) {


should the core logic related to addVersion & deleteVersion be kept in PackageStore or PackageAPI for now (if earlier comment is chosen to be addressed)

that way, this class remains as thin adapter only.

jaykay12 · 2026-10-29T19:16:07Z

+    return response;
+  }
+
+  private void syncToVersion(PackageStore packageStore, int expectedVersion) {


should this be kept as package private function inside PackageStore?

[reason]
this function mutates - packageStore.pkgs, ideally we can keep that ownership from within packageStore? if this function moves inside packageStore, we can esure package.pkgs is private to that class & no one changes its state from outside other than its own functions.

jaykay12 · 2026-10-29T19:24:49Z

-            solrClient, PackageUtils.PACKAGE_PATH, "{\"refresh\": \"" + packageName + "\"}");
-      } catch (Exception ex) {
+        new PackageApi.RefreshPackage(packageName).process(solrClient);
+      } catch (Exception ex) { // postJsonToSolr above declares a plain throws Exception


this code comment still valid?

jaykay12 · 2026-10-29T19:28:13Z

+/** Response for the get-a-specific-package API. */
+public class GetPackageResponse extends SolrJerseyResponse {
+
+  @JsonProperty("result")


[info] why the key name as "result", why not just "packageInfo" here?

jaykay12 · 2026-10-29T19:28:51Z

+/** Response for the package listing API. */
+public class ListPackagesResponse extends SolrJerseyResponse {
+
+  @JsonProperty("result")


[question] why not "packages" as the key?

jaykay12 · 2026-10-29T19:31:06Z

-    @JsonProperty(required = true)
-    public List<String> files;
+  @JsonProperty("version")
+  @Schema(description = "The version string for this package version.", required = true)


my local IntelliJ showed this warning.

please see, if applicable here.

thanks, going to look....

Copilot AI and others added 8 commits March 1, 2026 13:42

Initial plan

a86cf71

Migrate PackageAPI from @EndPoint/@command to JAX-RS annotations

744e8ff

Co-authored-by: epugh <[email protected]>

Fix PackageAPIJaxRsTest to use generated request classes and check re…

cc26412

…sponse.error field Co-authored-by: epugh <[email protected]>

Extract magic numbers as named constants in PackageAPIJaxRs

5040f5b

Co-authored-by: epugh <[email protected]>

Rename PackageAPIJaxRs to PackageAPI and old PackageAPI to PackageStore

83c2f5c

Co-authored-by: epugh <[email protected]>

Additional migrations from the old "command" style to the new RESTful…

d71f199

… style

fix test

8994e03

github-actions Bot added documentation Improvements or additions to documentation tests cat:search cat:api cat:packagemanager labels Mar 2, 2026

epugh marked this pull request as ready for review March 2, 2026 19:36

doc change

199b0f3

gerlowskija reviewed Apr 6, 2026

View reviewed changes

epugh added 8 commits April 25, 2026 07:12

Merge remote-tracking branch 'upstream/main' into copilot/migrate-pac…

463f590

…kageapi-to-jax-rs

Updates from merging in latest code from main.

ae94dd3

PackageAPI and PackageApis super confusing.

62212c3

Rename PackageAPI to ClusterPackage to follow naming pattern of other V2 apis.

Fix up expectedVersion property that was missing.

30ab7cc

Add test, revamp description.

Use our generated solrj code instead of hand crafting.

99d90e7

tidy

7967574

Small cleanups.

7491730

Now have a JIRA issue

deb2142

epugh changed the title ~~Migrate PackageAPI endpoints from @EndPoint/@Command to JAX-RS~~ SOLR-18212: Migrate PackageAPI endpoints from @EndPoint/@Command to JAX-RS Apr 25, 2026

epugh added 2 commits April 25, 2026 14:18

shockingly, we had these unused objects

2578d26

Don't need fancy instantiate method!

bf46dc7

epugh removed stale PR not updated in 60 days closed-stale Closed after being stale for 60 days labels Aug 28, 2026

epugh added 3 commits August 28, 2026 14:18

Merge remote-tracking branch 'upstream/main' into copilot/migrate-pac…

702b181

…kageapi-to-jax-rs

Bring this API up to date, following our conventions. Better path /ap…

1cfc294

…i/cluster/packages and errors.

add jira

b51a155

epugh requested a review from gerlowskija August 28, 2026 18:55

tidy

742b0ba

jaykay12 added 2 commits October 20, 2026 02:51

Merge branch 'main' into copilot/migrate-packageapi-to-jax-rs

59c1c26

precommit works now

47fd06e

github-actions Bot added the cat:cli label Oct 19, 2026

epugh and others added 7 commits October 28, 2026 08:29

Merge branch 'main' into copilot/migrate-packageapi-to-jax-rs

aa2d56e

fix the pathing and make GET actually not mutate state!

2445ef1

jaykay12 reviewed Oct 29, 2026

View reviewed changes

Conversation

epugh commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New REST endpoints

Key structural changes

Uh oh!

gerlowskija commented Apr 3, 2026

Uh oh!

epugh commented Apr 3, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

epugh commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

epugh commented Aug 28, 2026

Uh oh!

epugh commented Aug 28, 2026

Uh oh!

epugh commented Aug 28, 2026

Uh oh!

jaykay12 commented Oct 16, 2026

Uh oh!

epugh commented Oct 17, 2026

Uh oh!

epugh commented Oct 28, 2026

Uh oh!

jaykay12 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaykay12 Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

epugh commented Mar 2, 2026 •

edited

Loading

epugh commented Apr 25, 2026 •

edited

Loading

jaykay12 left a comment •

edited

Loading

jaykay12 Oct 29, 2026 •

edited

Loading